5.1.1. [RAC_REST_FORMAT_001] Utilizzo oggetti JSON¶

Nella tecnologia REST la comunicazione DOVREBBE avvenire tramite oggetti JSON RFC 8259 con il relativo media-type application/json.

È possibile fare eccezione in presenza di specifiche in cui gli oggetti di comunicazione sono formalizzati in forma diversa da JSON (es. INSPIRE, HL7).

5.1.2. [RAC_REST_FORMAT_002] Codificare dati strutturati con oggetti JSON¶

I dati strutturati in formato JSON RFC 8259 DOVREBBERO essere trasferiti tramite oggetti, in modo da permettere l’estensione retrocompatibile della response con ulteriori attributi, ad esempio paginazione.

Cioè:

• il payload di una response contenente una entry ritorna un oggetto

{
        "given_name": "Paolo",
        "last_name": "Rossi",
        "id": 313
}

• il payload di una response contenente più entry ​ritorna un oggetto contenente una lista​ e non direttamente una lista.

{
        "items": [
                {
                        "given_name": "Carlo",
                        "family_name": "Bianchi",
                        "id": 314
                },
                {
                        "given_name": "Giuseppe",
                        "family_name": "Verdi",
                        "id": 315
                }
        ]
}

5.1.3. [RAC_REST_FORMAT_003] Convenzioni di rappresentazione¶

DEVONO usarsi le seguenti convenzioni di rappresentazione:

• I booleani non DEVONO essere null.
• Gli array vuoti non DEVONO essere null, ma liste vuote, ad es. [].
• Le enumeration DEVONO essere rappresentate da stringhe non nulle.

5.1.4. [RAC_REST_FORMAT_004] Definire format quando si usano i tipi Number ed Integer¶

I numeri e gli interi DEVONO indicare la dimensione utilizzando il parametro format.

La seguente tabella - non esaustiva - elenca un set minimo di formati.

Le implementazioni DEVONO utilizzare il tipo più adatto.

5.1.5. [RAC_REST_FORMAT_005] Usare link relations registrate¶

DEVONO usarsi le specifiche indicate in IANA registered link relations [1] per rappresentare link e riferimenti a risorse HTTP esterne.